<?php
// $Id$
/**
 * This file contains {@link NodeDef} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');

phpCR::loadInterface('NodeType', '/nodetype');

if (phpCR::getLevel() >= 2) {
    phpCR::loadClass('OnParentVersionAction', '/version');
}


/**
 * A {@link Node} definition. Used in node typed definition
 *
 * @see NodeType::getChildNodeDefs(), Node::getDefinition()
 *
 * @see Workspace::getAccessManager(), AccessManager
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface NodeDef
{
   /**
    * Gets the node type that contains the declaration of this
    * {@link NodeDef}.
    *
    * @return object
    *   A {@link NodeType} object.
    */
    public function getDeclaringNodeType();
    
    
   /**
    * Gets the name of the child {@link Node}. 
    *
    * If NULL, this {@link NodeDef} defines a residual set of
    * child {@link Node}s. That is, it defines the characteristics of all those 
    * child nodes with names apart from the names explicitly used in other
    * property or child node definitions.
    *
    * @return string|null
    *   A string or NULL.
    */
    public function getName();
    
    
   /**
    * Gets the minimum set of primary node types that the child node must have.
    *
    * Returns an array to support those implementations with multiple
    * inheritance. The simplest case would be to return nt:base,
    * which is the base of all primary node types and therefore, in this
    * context, represents the least restrictive requirement.
    *
    * A {@link Node} must still have only one assigned primary {@link NodeType},
    * though this attribute can restrict that {@link NodeType} by taking 
    * advantage of any inheritance hierarchy that the implementation may 
    * support.
    *
    * @return array
    *   An array of {@link NodeType} objects.
    */
    public function getRequiredPrimaryTypes();
    
    
   /**
    * Gets the default primary {@link NodeType} that will be assigned to the
    * child node if it is created without an explicitly specified primary 
    * {@link NodeType}.
    *
    * This {@link NodeType} must be a subtype of (or the same type as) the 
    * {@link NodeType}s returned by {@link getRequiredPrimaryTypes()}.
    *
    * @return object
    *   A {@link NodeType}.
    */
    public function getDefaultPrimaryType();
    
    
   /**
    * Gets the minimum set of mixin {@link NodeType}s that the child
    * {@link Node} must have.
    *
    * @return array
    *   An array of {@link NodeType} objects.
    */
    public function getRequiredMixinTypes();
    
    
   /**
    * Gets the default set of mixin {@link NodeType}s that will be assigned to 
    * the child {@link Node} upon creation.
    *
    * This set of mixin node types must include at least those, or
    * subtypes of those, returned by {@link getRequiredMixinTypes()}.
    *
    * @return array 
    *   An array of {@link NodeType} objects.
    */
    public function getDefaultMixinTypes();
    
    
   /**
    * Reports whether the child {@link Node} is to be automatically created when
    * its parent {@link Node} is created. 
    *
    * If set to TRUE then this {@link NodeDef} must not be a 
    * residual set definition but must specify an actual child {@link Node}
    * name. This child node may be of a {@link NodeType} that specifies further
    * auto-created child {@link Node}s.  In such a case a chain of {@link Node}s
    * will be created.
    *
    * @return bool
    */
    public function isAutoCreate();
    
    
   /**
    * Reports whether the child {@link Node} is mandatory. 
    *
    * A mandatory {@link Property} is one that, if its parent {@link Node}
    * exists, must also exist. It cannot be removed through this API except by 
    * removing its parent.  
    *
    * An attempt to save a {@link Node} that has a mandatory child {@link Node}
    * without first creating that child {@link Node}, will throw a 
    * {@link ConstraintViolationException} on {@link Node::save()}.
    *
    * If a child node is mandatory then the following restrictions must be
    * enforced:
    * <ul>
    *   <li>If autoCreate is FALSE then the client
    *       must ensure that the child {@link Node} is created before the parent
    *       {@link Node} is saved, otherwise a 
    *       {@link ConstraintViolationException} will be thrown on 
    *       {@link Node::save()}.</li>
    *   <li>Once created, the child {@link Node} cannot be removed without 
    *       removing its parent {@link Node}, otherwise a 
    *       {@link ConstraintViolationException} is thrown on 
    *       {@link Node::save()}.</li>
    * </ul>
    *
    * @return bool
    */
    public function isMandatory();
    
    
   /**
    * Gets the on-parent-version status of the child node.
    *
    * This governs what to do if the parent {@link Node} of this child 
    * {@link Node} is versioned; an {@link OnParentVersionAction}.
    *
    * @return int
    */
    public function getOnParentVersion();
    
    
   /**
    * Reports whether the child {@link Node} is read-only.
    *
    * A read-only {@link Node} is one that cannot be changed (i.e., have child
    * {@link Node}s or {@link Property}s added or removed) through this API.
    * However, it may be altered by the implementation itself through some 
    * mechanism not defined by this specification.
    *
    * @return bool
    */
    public function isReadOnly();
    
    
   /**
    * Reports whether this {@link Node} is the primary child {@link Item} of 
    * its parent {@link Node}.
    *
    * Since any given {@link Node} may have either zero or one primary child
    * {@link Item}s, this means that a maximum of one {@link PropertyDef} or
    * {@link NodeDef} within a particular {@link NodeType} may return 
    * TRUE on this call. 
    *
    * The primary child {@link Item} flag is used by the method 
    * {@link Node::getPrimaryItem()}.
    *
    * @return bool.
    */
    public function isPrimaryItem();
    
    
   /**
    * Reports whether this child {@link Node} can have same-name siblings. 
    *
    * In other words, whether the parent {@link Node} can have more than one 
    * child {@link Node} of this name.
    *
    * @return bool
    */
    public function allowSameNameSibs();
}

